package com.srmt.document.api;

import com.srmt.document.model.TableData;
import com.srmt.document.model.RowData;
import com.srmt.document.model.ColumnData;
import com.srmt.document.exception.ContentException;
import com.srmt.document.exception.TableException;
import com.srmt.document.exception.CellException;
import java.util.List;

/**
 * 内容读取接口
 * 提供文档内容的各种读取操作
 * 
 * @author YourCompany
 * @since 1.0.0
 */
public interface ContentReader {
    
    // ============ 文本读取 ============
    
    /**
     * 读取指定文字后的文本内容
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字
     * @return 文本内容
     * @throws ContentException 操作失败时抛出
     */
    String readTextAfter(String docId, String anchorText) throws ContentException;
    
    /**
     * 读取指定文字前的文本内容
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字
     * @return 文本内容
     * @throws ContentException 操作失败时抛出
     */
    String readTextBefore(String docId, String anchorText) throws ContentException;
    
    /**
     * 读取指定范围内的文本内容
     * 
     * @param docId 文档ID
     * @param startAnchor 开始锚点文字
     * @param endAnchor 结束锚点文字
     * @return 文本内容
     * @throws ContentException 操作失败时抛出
     */
    String readTextBetween(String docId, String startAnchor, String endAnchor) throws ContentException;
    
    /**
     * 读取文档全部文本内容
     * 
     * @param docId 文档ID
     * @return 文档全部文本内容
     * @throws ContentException 操作失败时抛出
     */
    String readAllText(String docId) throws ContentException;
    
    /**
     * 搜索文本内容
     * 
     * @param docId 文档ID
     * @param searchText 要搜索的文本
     * @return 匹配的文本位置列表（包含上下文）
     * @throws ContentException 操作失败时抛出
     */
    List<String> searchText(String docId, String searchText) throws ContentException;
    
    // ============ 表格读取 ============
    
    /**
     * 读取指定文字后的表格
     * 
     * @param docId 文档ID
     * @param anchorText 锚点文字
     * @return 表格数据
     * @throws TableException 操作失败时抛出
     */
    TableData readTableAfter(String docId, String anchorText) throws TableException;
    
    /**
     * 读取文档中的所有表格
     * 
     * @param docId 文档ID
     * @return 所有表格数据列表
     * @throws TableException 操作失败时抛出
     */
    List<TableData> readAllTables(String docId) throws TableException;
    
    /**
     * 读取表格指定行范围的数据
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param startRow 开始行（从1开始）
     * @param endRow 结束行（包含）
     * @return 行数据列表
     * @throws TableException 操作失败时抛出
     */
    List<RowData> readTableRows(String docId, String tableAnchor, int startRow, int endRow) 
            throws TableException;
    
    /**
     * 读取表格指定列范围的数据
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param startColumn 开始列（从1开始）
     * @param endColumn 结束列（包含 从1开始）
     * @return 列数据列表
     * @throws TableException 操作失败时抛出
     */
    List<ColumnData> readTableColumns(String docId, String tableAnchor, int startColumn, int endColumn) 
            throws TableException;
    
    /**
     * 获取表格的行数
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @return 表格行数
     * @throws TableException 操作失败时抛出
     */
    int getTableRowCount(String docId, String tableAnchor) throws TableException;
    
    /**
     * 获取表格的列数
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @return 表格列数
     * @throws TableException 操作失败时抛出
     */
    int getTableColumnCount(String docId, String tableAnchor) throws TableException;
    
    // ============ 单元格读取 ============
    
    /**
     * 读取指定单元格内容
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param row 行坐标（从1开始）
     * @param column 列坐标（从1开始）
     * @return 单元格内容
     * @throws CellException 操作失败时抛出
     */
    String readCellContent(String docId, String tableAnchor, int row, int column) 
            throws CellException;
    
    /**
     * 批量读取单元格内容
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param startRow 开始行
     * @param startColumn 开始列 1 开始
     * @param endRow 结束行 1 开始
     * @param endColumn 结束列
     * @return 二维列表的单元格内容
     * @throws CellException 操作失败时抛出
     */
    List<List<String>> readCellsContent(String docId, String tableAnchor, 
                                        int startRow, int startColumn, 
                                        int endRow, int endColumn) throws CellException;
    
    /**
     * 读取包含指定文字的合并单元格右侧相邻列的单元格内容
     * 
     * 该方法会查找表格中包含指定文字的合并单元格，然后读取该合并单元格
     * 右侧紧邻列中对应行的单元格内容。例如，如果合并单元格跨越第1-3行，
     * 则会返回其右侧列第1-3行的内容。
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字，用于定位表格
     * @param cellText 合并单元格中包含的文字，用于定位合并单元格
     * @return 右侧相邻列的单元格内容列表
     * @throws CellException 操作失败时抛出
     */
    List<String> readCellsNextToMergedCell(String docId, String tableAnchor, String cellText) 
            throws CellException;
    
    /**
     * 检查单元格是否为合并单元格
     * 
     * @param docId 文档ID
     * @param tableAnchor 表格锚点文字
     * @param row 行坐标 >= 1
     * @param column 列坐标 >= 1
     * @return true如果是合并单元格，否则false
     * @throws CellException 操作失败时抛出
     */
    boolean isMergedCell(String docId, String tableAnchor, int row, int column) 
            throws CellException;
    

    /**
     * 统计文档字数
     * 
     * @param docId 文档ID
     * @return 文档总字数
     * @throws ContentException 操作失败时抛出
     */
    int getWordCount(String docId) throws ContentException;
}